<!-- Copyright 2004 The Apache Software Foundation

     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
     You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License. -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
                     
  <meta http-equiv="Content-Language" content="en-us">
  <title>XMLBean Task</title>
</head>
  <body>
            
<h2><a name="xmlbean">XMLBean</a></h2>
           
<h3>Description</h3>
              
<p>Compile a set of XSDs and/or WSDLs into xbeans. This is useful for building
 an XMLBean jar from .XSD and .WSDL files. &nbsp;The task can also generate
 the source code that makes up the xbean type system specified by the schema
 files if desired.</p>
              
<p><b>Note:</b> This task depends on an external library not included in
the  Ant distribution called xbean.jar. &nbsp;It can be found in the XMLBeans
 developer kit at <a
 href="http://xml.apache.org/xmlbeans/">http://xml.apache.org/xmlbeans/</a>. 
The build script will need to include a taskdef for xmlbean, which could look
like this:<br>
 </p>
 
<pre>&nbsp;&nbsp;&nbsp; &lt;taskdef name="xmlbean" classname="org.apache.xmlbeans.impl.tool.XMLBean" classpath="path/to/xbean.jar"/&gt;</pre>
 
<p>   </p>
           
<p>It is possible to refine the set of files that are being processed. This 
  can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, 
  <i>excludesfile</i> and <i>defaultexcludes</i> attributes. With the <i>includes</i> 
  or <i>includesfile</i> attribute you specify the files you want to have 
included  by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute 
is  used to specify the files you want to have excluded. This is also done 
with  patterns. And finally with the <i>defaultexcludes</i> attribute, you 
can specify whether you want to use default exclusions or not. See the section 
 on <a
 href="http://ant.apache.org/manual/dirtasks.html#directorybasedtasks">directory
 based tasks</a>, on how the inclusion/exclusion of files works, and how
to  write patterns.</p>
           
<p>This task forms an implicit <a
 href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a> 
and supports all   attributes of <code>&lt;fileset&gt;</code> (<code>dir</code> 
  becomes <code>basedir</code>)   as well as the nested <code>&lt;include&gt;</code>, 
  <code>&lt;exclude&gt;</code>   and <code>&lt;patternset&gt;</code> elements.</p>
              
<h3>Parameters</h3>
           
<table border="1" cellpadding="2" cellspacing="0">
        <tbody>
         <tr>
          <td valign="top"><b>Attribute</b></td>
          <td valign="top"><b>Description</b></td>
          <td align="center" valign="top"><b>Required</b></td>
        </tr>
        <tr>
          <td valign="top">schema</td>
          <td valign="top">A file that points to either an individual schema
 file or a directory of files. &nbsp;Not a path reference. &nbsp;If multiple
 schema files need to be built together, use a nexted fileset instead of
setting  schema.</td>
          <td align="center" valign="top">Yes, unless a fileset element is
 nested.</td>
        </tr>
        <tr>
          <td valign="top">destfile</td>
          <td valign="top">Define the name of the jar file created.&nbsp; 
For instance, "myXMLBean.jar" will output the results of this task into a 
jar with the same name.</td>
          <td align="center" valign="top">No, default is "xmltypes.jar".</td>
        </tr>
        <tr>
          <td valign="top">download</td>
          <td valign="top">Set to true to permit the compiler to download 
URLs for imports and includes.&nbsp; Defaults to false, meaning all imports 
and includes must be copied locally.<br>
        </td>
          <td align="center" valign="top">No, default is false.</td>
        </tr>
        <tr>
          <td valign="top">failonerror</td>
          <td valign="top">     Determines whether or not the ant target
will  continue if the XMLBean creation encounters a build error.<br>
        </td>
          <td align="center" valign="top">No, default is true.</td>
        </tr>
      <tr>
        <td valign="top">verbose<br>
        </td>
        <td valign="top">Controls the amount of build message output.<br>
        </td>
        <td valign="top" align="center">No, default is true.<br>
        </td>
      </tr>
      <tr>
        <td valign="top">typesystemname<br>
        </td>
        <td valign="top">The name of the package that the TypeSystemHolder
class should be generated in.&nbsp; Normally this should be left unspecified.
None of the xml beans are generated in this package. Use .xsdconfig files
to modify xml bean package or class names.<br>
        </td>
        <td valign="top" align="center">No<br>
        </td>
      </tr>
      <tr>
        <td valign="top">classgendir<br>
        </td>
        <td valign="top">Set a location to generate .class files into.<br>
        </td>
        <td valign="top" align="center">No<br>
        </td>
      </tr>
      <tr>
        <td valign="top">srconly<br>
        </td>
        <td valign="top">A value of true means that only source will be generated.<br>
        </td>
        <td valign="top" align="center">No, default is false.<br>
        </td>
      </tr>
      <tr>
        <td valign="top">srcgendir<br>
        </td>
        <td valign="top">Set a location to generate .java files into.<br>
        </td>
        <td valign="top" align="center">No<br>
        </td>
      </tr>
      <tr>
          <td valign="top">classpath</td>
          <td valign="top">The classpath to use if schemas in the fileset
import definitions that are supplied by other compiled xml beans JAR files,
or if .java files are in the schema fileset.  Also supports a nested classpath.</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">classpathref</td>
          <td valign="top">Adds a classpath, given as <a
 href="http://ant.apache.org/manual/using.html#references">reference</a>
to a path defined elsewhere.</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">includes</td>
          <td valign="top">Comma- or space-separated list of patterns of
files   that must be included.       All files are included when omitted.</td>
          <td valign="top" align="center">No</td>
        </tr>
        <tr>
          <td valign="top">includesfile</td>
          <td valign="top">The name of a file. Each line of this file is
taken   to be       an include pattern</td>
          <td valign="top" align="center">No</td>
        </tr>
        <tr>
          <td valign="top">excludes</td>
          <td valign="top">Comma- or space-separated list of patterns of
files   that must be excluded.       No files (except default excludes) are
excluded   when omitted.</td>
          <td valign="top" align="center">No</td>
        </tr>
        <tr>
          <td valign="top">excludesfile</td>
          <td valign="top">The name of a file. Each line of this file is
taken   to be       an exclude pattern</td>
          <td valign="top" align="center">No</td>
        </tr>
        <tr>
          <td valign="top">defaultexcludes</td>
          <td valign="top">Indicates whether default excludes should be used
  or not       ("yes"/"no"). Default excludes are used when omitted.</td>
          <td valign="top" align="center">No</td>
        </tr>
        <tr>
          <td valign="top">debug</td>
          <td valign="top">Indicates whether source should be compiled with
          debug information; defaults to <code>off</code>.  If set to
          <code>off</code>, <code>-g:none</code> will be passed on the
          command line for compilers that support it (for other compilers, no
          command line argument will be used).  If set to <code>true</code>,
          the value of the <code>debuglevel</code> attribute determines the
          command line argument.</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">debuglevel</td>
          <td valign="top">Keyword list to be appended to the <code>-g</code>
            command-line switch.  This will be ignored by all implementations except
            <code>modern</code> and <code>classic(ver &gt;= 1.2)</code>.
            Legal values are <code>none</code> or a comma-separated list of the
            following keywords:
            <code>lines</code>, <code>vars</code>, and <code>source</code>.
            If <code>debuglevel</code> is not specified, by default,
            nothing will be
            appended to <code>-g</code>.  If <code>debug</code> is not turned on,
            this attribute will be ignored.
          </td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">optimize</td>
          <td valign="top">Indicates whether source should be compiled with
            optimization; defaults to <code>off</code>.</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">includeAntRuntime</td>
          <td valign="top">Whether to include the Ant run-time libraries in the
            classpath; defaults to <code>yes</code>.</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">includeJavaRuntime</td>
          <td valign="top">Whether to include the default run-time
            libraries from the executing VM in the classpath;
            defaults to <code>no</code>.</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">fork</td>
          <td valign="top">Whether to execute <code>javac</code> using the
            JDK compiler externally; defaults to <code>yes</code>.</td>
          <td align="center" valign="top">No, default is true</td>
        </tr>
        <tr>
          <td valign="top">executable</td>
          <td valign="top">Complete path to the <code>javac</code>
            executable to use in case of <code>fork=&quot;yes&quot;</code>.
            Defaults to the compiler of the Java version that is currently
            running Ant.  Ignored if <code>fork=&quot;no&quot;</code></td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">memoryInitialSize</td>
          <td valign="top">The initial size of the memory for the underlying VM,
            if <code>javac</code> is run externally; ignored otherwise. Defaults
            to the standard VM memory setting.
            (Examples: <code>83886080</code>, <code>81920k</code>, or
            <code>80m</code>)</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">memoryMaximumSize</td>
          <td valign="top">The maximum size of the memory for the underlying VM,
            if <code>javac</code> is run externally; ignored otherwise. Defaults
            to the standard VM memory setting.
            (Examples: <code>83886080</code>, <code>81920k</code>, or
            <code>80m</code>)</td>
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">compiler</td>
          <td valign="top">The compiler implementation to use.
            If this attribute is not set, the value of the
            <code>build.compiler</code> property, if set, will be used.
            Otherwise, the default compiler for the current VM will be used.
          <td align="center" valign="top">No</td>
        </tr>
        <tr>
          <td valign="top">ignoreDuplicatesInNamespaces</td>
          <td valign="top">Comma separated list of one or more namespaces
          in which duplicate definitions are to be ignored.
          </td>
          <td align="center" valign="top">No</td>
        </tr>
                    
  </tbody>     
</table>
                 
<h3>Example</h3>
           
<blockquote>               Be sure to define the task in your script, like 
this:<br>
   
  <pre>&lt;taskdef name="xmlbean" classname="org.apache.xmlbeans.impl.tool.XMLBean" classpath="path/to/xbean.jar"/&gt;</pre>
   
  <pre><br>&lt;xmlbean schema="schemas" destfile="Schemas.jar"/&gt;<br></pre>
  Builds all the schemas in the schemas directory and creates a jar called
 'Schemas.jar'.<br>
                    
  <pre>&lt;xmlbean schema="schemas/ourSchema.xsd" download="true"/&gt;<br></pre>
  Compiles the schema 'ourShema.xsd' into the default jar 'xmltypes.jar'. 
&nbsp;If &nbsp;any imports and includes are defined by remote URLs, they are
downloaded during the build.<br>
                       
  <h4>Using a fileset</h4>
                       
  <pre>&lt;xmlbean classgendir="${build.dir}" classpath="${class.path}"<br>      failonerror="true"&gt;<br>  &lt;fileset basedir="src" excludes="**/*.xsd"/&gt;<br>  &lt;fileset basedir="schemas" includes="**/*.*"/&gt;<br>&lt;/xmlbean&gt;<br></pre>
  Gathers all the files in the 'src' directory except .xsd files, along with
 every file in the 'schemas' directory and compiles them. The fileset can
include schema files that refer to previously compiled schema components.&nbsp;
The fileset can also contain .java files.&nbsp; The classpath parameter defines
the classpath necessary to resolve compiled schema and java references.<br>
  <br>
The built classes will go into ${build.dir}.<br>
                       
  <pre></pre>
           </blockquote>
           
<hr>      
       <br>
        <br>
 <br>
</body>
</html>
